/*
 * $Id: QECallsign.h 249 2008-09-09 13:58:25Z jon $
 *
 * Copyright Jon Gordon
 * Created by Jon Gordon on 12/28/07.
 *
 * Permission is hereby granted, free of charge, to any person obtaining 
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including 
 * without limitation the rights to use, copy, modify, merge, publish, 
 * distribute, sublicense, and/or sell copies of the Software, and to 
 * permit persons to whom the Software is furnished to do so, subject to 
 * the following conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#import <Cocoa/Cocoa.h>

/*
 * Model object, primitive data type representing a callsign, including
 * modifiers such as temporary or portable prefixes or suffixes and
 * designators such as "/M", "/MM" (maritime mobile), and "/P".
 *
 * This class is currently a dummy, having no instance variables or
 * methods, but it includes several class methods useful for
 * validating character strings as possible call signs.
 *
 * A distinction is made between a "base" call sign and a call sign
 * as such.  A base callsign is a simple call sign, such as appears
 * on the original license, without any portable, mobile, temporary,
 * or other designators.  Call signs can include such designators.
 * All valid base call signs are valid call signs, but not the other
 * way around.
 *
 * As a rule of thumb, if it includes a slash, it can be a call sign,
 * but not a base call sign.  If it lacks a slash, it can be either.
 */
@interface QECallsign : NSObject {
}
/*
 * Determines whether a callsign can be interpreted as a valid callsign,
 * taking into account all extra prefixes and suffixes (e.g., indicating
 * portable or mobile operation or operation under a reciprocal operating
 * agreement).
 *
 * parameter:
 *  callsign - string to be evaluated as a potentially valid callsign
 *
 * return:
 *  YES if the parameter can be interpreted as a valid callsign, NO
 *  otherwise.
 */
+ (BOOL)isValidCallsign:(NSString *)callsign;

/*
 * Determines whether a callsign can be interpreted as a valid callsign,
 * taking into account all extra prefixes and suffixes (e.g., indicating
 * portable or mobile operation or operation under a reciprocal operating
 * agreement).  This method supports the validateXXX interface as part
 * of Cocoa's key-value coding support.
 *
 * If the ioValue parameter points to a valid callsign or a string that
 * could be corrected to be a valid callsign, the function returns YES,
 * and ioValue points to a valid callsign.  If the string cannot be read
 * as a valid callsign, and if outError is not nil, then an NSError
 * object describing the pattern is returned in *outError.
 *
 * In this implementation, "correcting" a callsign includes converting
 * all letters to upper case.
 *
 * parameters:
 *  ioValue - pointer to string that is to be evaluated as a potentially
 *            valid callsign; if the original value is invalid, but
 *            can be corrected, the corrected version will be passed
 *            out in this parameter
 * outError - pointer to NSError object or nil; if not nil, and ioValue
 *            cannot be read as or converted to a valid callsign, a
 *            instance of NSError will be passed out here
 *
 * return:
 *  YES if the parameter can be interpreted as a valid callsign, NO
 *  otherwise.
 */
+ (BOOL)isValidCallsign:(id *)ioValue error:(NSError **)outError;

/*
 * Determines whether a callsign can be interpreted as a valid base
 * callsign, which is a callsign as it appears on a ticket (i.e., without
 * slashes, temporary designators, portable or mobile designators, or
 * the like).
 *
 * parameter:
 *  callsign - string to be evaluated as a potentially valid callsign
 *
 * return:
 *  YES if the parameter can be interpreted as a valid callsign, NO
 *  otherwise.
 */
+ (BOOL)isValidBaseCallsign:(NSString *)callsign;

/*
 * Determines whether a callsign can be interpreted as a valid base
 * callsign, which is a callsign as it appears on a ticket (i.e., without
 * slashes, temporary designators, portable or mobile designators, or
 * the like).  This method supports the validateXXX interface as part
 * of Cocoa's key-value coding support.
 *
 * If the ioValue parameter points to a valid callsign or a string that
 * could be corrected to be a valid callsign, the function returns YES,
 * and ioValue points to a valid callsign.  If the string cannot be read
 * as a valid callsign, and if outError is not nil, then an NSError
 * object describing the pattern is returned in *outError.
 *
 * In this implementation, "correcting" a callsign includes converting
 * all letters to upper case.
 *
 * parameters:
 *  ioValue - pointer to string that is to be evaluated as a potentially
 *            valid callsign; if the original value is invalid, but
 *            can be corrected, the corrected version will be passed
 *            out in this parameter
 * outError - pointer to NSError object or nil; if not nil, and ioValue
 *            cannot be read as or converted to a valid callsign, a
 *            instance of NSError will be passed out here
 *
 * return:
 *  YES if the parameter can be interpreted as a valid callsign, NO
 *  otherwise.
 */
+ (BOOL)isValidBaseCallsign:(id *)ioValue error:(NSError **)outError;
@end
